Get1NamedResource

Get1NamedResource
Header:	Resources.h		Carbon status:	Supported

Gets a named resource in the current resource file.

Handle Get1NamedResource (
    ResType theType, 
    ConstStr255Param name
);

theType: The resource type of the resource about which you wish to retrieve data.
name: A name that uniquely identifies the resource about which you wish to retrieve data.

function result

If the function finds an entry for the resource in the current resource file’s resource map and the entry contains a valid handle, the function returns that handle. If the entry contains a handle whose value is NULL, and if you haven’t called the SetResLoad function with the load parameter set to FALSE, Get1NamedResource attempts to read the resource into memory. If it can’t find the resource data, the function returns NULL, and the ResError function returns the result code resNotFound. The Get1NamedResource function also returns NULL if the resource data to be read into memory won’t fit, in which case ResError returns an appropriate Memory Manager result code.

If you call this function with a resource type that can’t be found in the resource map of the current resource file, the function returns NULL, but ResError returns the result code noErr. You should always check that the value of the returned handle is not NULL.

DISCUSSION

The function searches the current resource file’s resource map in memory for the specified resource. You can change the search order by calling the UseResFile function before Get1NamedResource.

To include ROM-resident system resources in the Resource Manager’s search of the resource maps for open resource forks, use the RGetResource function.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.